   This file documents the Emacs/W3 World Wide Web browser.

   Copyright (C) 1993, 1994, 1995, 1996 William M. Perry Copyright (C)
1996, 1997 Free Software Foundation

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

W3
**

   Users can browse the World Wide Web from within Emacs by using
Emacs/W3.  All of the widely used (and even some not very widely used)
URL schemes are supported, and it is very easy to add new methods as the
need arises.

   Emacs/W3 provides some core functionality that can be readily re-used
from any program in Emacs.  Users and other package writers are
encouraged to Web-enable their applications and daily work routines
with the library.

   Emacs/W3 is completely customizable, both from Emacs-Lisp and from
stylesheets Stylesheets  If there is any aspect of Emacs/W3 that
cannot be modified to your satisfaction, please send mail to the
w3-beta@indiana.edu mailing list with any suggestions.  See Reporting Bugs

   This manual corresponds to Emacs/W3 v4.0pre.7

Appendices:

Indices:

Getting Started
***************

   If installed correctly, starting Emacs/W3 is quite painless.  Just
type `M-x w3' in a running Emacs session.  This will retrieve the
default page that has been configured (see Preferences Panel.) - by
default the documentation for Emacs/W3 at Indiana University.

   If the default page is not retrieved correctly at startup, you will
have to do some customization (see Preferences Panel.).

   Once started, you can use the mouse and the menu or use the following
key commands (for more commands and more detail, see Basic Usage).

move forward
     press the space bar,

move backwards
     press the backspace key,

move to the next HTML reference on the page
     press the `TAB' key,

move to the previous HTML reference on the page
     press the `SHIFT' and `TAB' keys at the same time.  If this does
     not work (some text terminals cannot distinguish between `TAB' and
     `SHIFT-TAB', pressing the `ALT' and `TAB' keys should also work.

follow a link
     put the cursor over it and press the `RETURN' key, or
     click the left mouse button on it,

fetch a URL
     press the `Control' and `o' keys at the same time,
     type the URL, and then press the `RETURN' key,

return to the last URL you were at
     press the `l' key,

quit W3 mode
     press the `q' key.

Downloading
===========

   :: WORK :: What you need, and why
:: WORK :: Where to download Emacs, XEmacs, various platforms
:: WORK :: Where to download Emacs/W3
:: WORK :: Where to download related utilities (netpbm, xv, gimp, etc.)

Building and Installing
=======================

   :: WORK :: Document makefile variables
:: WORK :: Document what gets installed where, why

Startup Files
=============

   :: WORK :: startup files
This section should document where Emacs/W3 looks for its startup files,
and what each one does.  'profile' 'stylesheet' 'hotlist' 'history' etc.

Preferences Panel
=================

   :: WORK :: pref panel
This should document the quick preferences panel.  M-x
w3-preferences-edit

Basic Usage
***********

   Emacs/W3 is similar to the Info package all Emacs users hold near and
dear to their hearts (see Info (info), for a description of
Info).  Basically, `space' and `backspace' control scrolling, and
`return' or the middle mouse button follows a hypertext link.  The
`tab' and `Meta-tab' keys maneuver around the various links on the page.

   NOTE: Starting with Emacs/W3 4.0, form entry areas in a page can be
typed directly into.  This is one of the main differences in navigation
from version 2.0.  If you are used to using the `f' and `b' keys to
navigate around a buffer, I suggest training yourself to always use
`tab' and `M-tab' - it will save time and frustration on pages with
lots of form fields.

   By default, hypertext links are surrounded by '[[' and ']]' on
non-graphic terminals (VT100, DOS window, etc.).  On a graphics
terminal, the links are in shown in different colors.  See
Stylesheets for information on how to change this.

   There are approximately 50 keys bound to special Emacs/W3 functions.
The basic rule of thumb regarding keybindings in Emacs/W3 is that a
lowercase key takes an action on the current document, and an uppercase
key takes an action on the document pointed to by the hypertext link
under the cursor.

   There are several areas that the keybindings fall into: movement,
information, action, and miscellaneous.

Movement
========

   All the standard Emacs bindings for movement are still in effect,
with a few additions for convenience.

`space'
     Scroll downward in the buffer.  With prefix arg, scroll down that
     many screenfuls.

`backspace'
     Scroll upward in the buffer.  With prefix arg, scroll up that many
     screenfuls.

`<'
     Goes to the start of document

`>'
     Goes to the end of document

`Meta-tab, Shift-tab, b'
     Attempts to move backward one link area in the current document.
     Signals an error if no previous links are found.

`tab, f, n'
     Attempts to move forward one link area in the current document.
     Signals an error if no more links are found.

`B'
     Move backwards in the history stack.

`F'
     Move forwards in the history stack.

`l'
     Return to the last buffer shown before this buffer.

`q'
     Kill this buffer.

`Q, u'
     Bury this buffer, but don't kill it

Information
===========

   These functions relate information about one or more links on the
current document.

`v'
     This shows the URL of the current document in the minibuffer.

`V'
     This shows the URL of the hypertext link under point in the
     minibuffer.

`i'
     Shows miscellaneous information about the currently displayed
     document.  This includes the URL, the last modified date, MIME
     headers, the HTTP response code, and any relationships to other
     documents.  Any security information is also displayed.

`I'
     Shows information about the URL at point.

`s'
     This shows the HTML source of the current document in a separate
     buffer.  The buffer's name is based on the document's URL.

`S'
     Shows the HTML source of the hypertext link under point in a
     separate buffer.  The buffer's name is based on the document's URL.

`k'
     This stores the current document's URL in the kill ring, and also
     in the current window-system's clipboard, if possible.

`K'
     Stores the URL of the document under point in the kill ring, and
     also in the current window-system's clipboard, if possible.

Action
======

   First, here are the keys and functions that bring up a new hypertext
page, usually creating a new buffer.
`m'
     Choose a link from the current buffer and follow it.  A
     completing-read is done on all the links, so `space' and `TAB' can
     be used for completion.

`return'
     Pressing return when over a hyperlink attempts to follow the link
     under the cursor.  With a prefix argument (`C-u'), this forces the
     file to be saved to disk instead of being passed off to other
     viewers or being parsed as HTML.

     Pressing return when over a form input field can cause
     auto-submission of the form.  This is for Mosaic and Netscape
     compatibility.  If there is only one item in the form other than
     submit or reset buttons, then the form will be submitted.

`Middle Mouse Button'
     Attempt to follow a hypertext link under the mouse cursor.
     Clicking on a form input field will prompt in the minibuffer for
     the data to insert into the input field.  Type checking is done,
     and the data is only entered into the form when data of the
     correct type is entered (ie: cannot enter 44 for 'date' field,
     etc).

`Control Middle Mouse Button, Meta return'
     Tries to retrieve the inlined image that is under point.  It
     ignores any form entry areas or hyperlinks, and blindly follows
     any inlined image.  Useful for seeing images that are meant to be
     used as hyperlinks when not on a terminal capable of displaying
     graphics.

`p'
     Prints out the current buffer in a variety of formats, including
     PostScript, HTML source, or formatted text.

`P'
     Prints out the URL under point in a variety of formats, including
     PostScript, HTML source, or formatted text.

`m'
     Selects a destination from a list of all the hyperlinks in the
     current buffer.  Use `space' and `tab' to complete on the links.

`r, g'
     Reloads the current document.  The position within the buffer
     remains the same (unless the document has changed since it was
     last retrieved, in which case it should be relatively close).
     This causes an unconditional reload from the remote server - the
     locally cached copy is not consulted.

`C-o'
     Prompts for a URL in the minibuffer, and attempts to fetch it.  If
     there are any errors, or Emacs/W3 cannot understand the type of
     link requested, the errors are displayed in a hypertext buffer.

`o'
     Opens a local file, interactively.  This prompts for a local file
     name to open.  The file must exist, and may be a directory.  If
     the requested file is a directory and `url-use-hypertext-dired' is
     `nil', then a dired-mode buffer is displayed.  If non`nil', then
     Emacs/W3 automatically generates a hypertext listing of the
     directory.  The hypertext mode is the default, so that all the
     keys and functions remain the same.

`M-s'
     Save a document to the local disk as HTML Source, Formatted Text,
     LaTeX Source, or Binary.

`Hv'
     If `url-keep-history' is non-`nil', then Emacs/W3 keeps track of
     all the URLs visited in an Emacs session.  This function takes all
     the links that are in that internal list, and formats them as
     hypertext links in a list.

   And here are the commands to move around between Emacs/W3 buffers:

`l'
     Goes to the last WWW buffer seen.

`q'
     Quits WWW mode.  This kills the current buffer and goes to the most
     recently visited buffer.

`u'
     This is similar to w3-quit, but the buffer is not killed, it is
     moved to the bottom of the buffer list (so it is the least likely
     to show up as the default with switch-to-buffer).  This is
     different from `w3-goto-last-buffer' in that it does not return to
     the last WWW page visited - it is the same as using
     `switch-to-buffer' - the buffer left in the window is fairly
     random.

`HB, B'
     Takes one step back along the path in the current history.  Has no
     effect if at the beginning of the session history.

`HF, F'
     Takes one step forward along the path in the current history.  Has
     no effect if at the end of the session history.

Miscellaneous
=============

`M-m'
     Mails the current document to someone.  Choose from several
     different formats to mail: formatted text, HTML source,
     PostScript, or LaTeX source.  When the HTML source is mailed, then
     an appropriate <base> tag is inserted at the beginning of the
     document so that relative links may be followed correctly by
     whoever receives the mail.

`M-M'
     Mails the document pointed to by the hypertext link under point to
     someone.  Choose from several different formats to mail: formatted
     text, HTML source, PostScript, or LaTeX source.  When the HTML
     source is mailed, then an appropriate <base> tag is inserted at
     the beginning of the document so that relative links may be
     followed correctly by whoever receives the mail.

`p'
     Prints the current document.  Choose from several different
     formats to print: formatted text, HTML source, PostScript (with
     ps-print), or by using LaTeX and dvips).

     When the formatted text is printed, the normal `lpr-buffer'
     function is called, and the variables `lpr-command' and
     `lpr-switches' control how the document is printed.

     When the HTML source is printed, then an appropriate <base> tag is
     inserted at the beginning of the document.  When postscript is
     printed, then the HTML source of the document is converted into
     LaTeX source.  There are several variables controlling what the
     final LaTeX document looks like.

     :: WORK :: Document the new LaTeX backend

    `w3-latex-use-latex2e'
          If non-`nil', configures the LaTeX engine to use the LaTeX2e
          syntax.  A `nil' value indicates that LaTeX 2.0.9
          compabibility will be used instead.

    `w3-latex-docstyle'
          The document style to use when printing or mailing converted
          HTML files in LaTeX.  Good defaults are: {article},
          [psfig,twocolumn]{article}, etc.

    `w3-latex-packages'
          List of LaTeX packages to include.  Currently this is only
          used if `w3-latex-use-latex2e' is non-`nil'.

    `w3-latex-use-maketitle'
          If non-`nil', the LaTeX engine will use real LaTeX title
          pages for document titles.

    `w3-latex-print-links'
          If non-`nil', prints the URLs of hypertext links as endnotes
          at the end of the document.  If set to `footnote', prints the
          URL's as footnotes on each page.

`P'
     Prints the document pointed to by the hypertext link under point.
     Please see the previous item for more information.

`M-x w3-insert-formatted-url'
     Insert a fully formatted HTML link into another buffer.  This gets
     the name and URL of either the current buffer, or, with a prefix
     arg, of the link under point, and construct the appropriate
     <a...>...</a> markup and insert it into the desired buffer.

`M-tab'
     Inserts the URL of the current document into another buffer.
     Buffer is prompted for in the minibuffer.  With prefix arg, uses
     the URL of the link under point.

`U'
     Selects one of the <LINK> tags from this document and fetch it.
     Links are attributes of a specific document, and can tell such
     things as who made the document, where a table of contents is
     located, etc.

     Link tags specify relationships between documents in two ways.
     Normal (forward) relationships (where the link has a REL="xxx"
     attribute), and reverse relationships (where the link has a
     REV="xxx" attribute).  This first asks what type of link to follow
     (Normal or Reverse), then does a `completing-read' on only the
     links that have that type of relationship.

Compatibility with other Browsers
*********************************

   Due to the popularity of several other browsers, Emacs/W3 offers an
easy transition to its much better way of life.  This ranges from being
able to share the same preferences files and disk cache to actually
emulating the keybindings used in other browsers.

Emulation
=========

   :: WORK :: Document lynx emulation
`Down arrow'
     Highlight next topic

`Up arrow'
     Highlight previous topic

`Right arrow, Return, Enter'
     Jump to highlighted topic

`Left arrow'
     Return to previous topic

`+'
     Scroll down to next page (Page-Down)

`-'
     Scroll up to previous page (Page-Up)

`SPACE'
     Scroll down to next page (Page-Down)

`b'
     Scroll up to previous page (Page-Up)

`C-A'
     Go to first page of the current document (Home)

`C-E'
     Go to last page of the current document (End)

`C-B'
     Scroll up to previous page (Page-Up)

`C-F'
     Scroll down to next page (Page-Down)

`C-N'
     Go forward two lines in the current document

`C-P'
     Go back two lines in the current document

`)'
     Go forward half a page in the current document

`('
     Go back half a page in the current document

`#'
     Go to Toolbar or Banner in the current document

`?, h'
     Help (this screen)

`a'
     Add the current link to a bookmark file

`c'
     Send a comment to the document owner

`d'
     Download the current link

`e'
     Edit the current file

`g'
     Goto a user specified URL or file

`i'
     Show an index of documents

`j'
     Execute a jump operation

`k'
     Show a list of key mappings

`l'
     List references (links) in current document

`m'
     Return to main screen

`o'
     Set your options

`p'
     Print the current document

`q'
     Quit

`/'
     Search for a string within the current document

`s'
     Enter a search string for an external search

`n'
     Go to the next search string

`v'
     View a bookmark file

`V'
     Go to the Visited Links Page

`x'
     Force submission of form or link with no-cache

`z'
     Cancel transfer in progress

`[backspace]'
     Go to the history Page

`='
     Show file and link info

`\'
     Toggle document source/rendered view

`!'
     Spawn your default shell

`*'
     Toggle image_links mode on and off

`['
     Toggle pseudo_inlines mode on and off

`]'
     Send an HTTP HEAD request for the current doc or link

`C-R'
     Reload current file and refresh the screen

`C-W'
     Refresh the screen

`C-U'
     Erase input line

`C-G'
     Cancel input or transfer

`C-T'
     Toggle trace mode on and off

`C-K'
     Invoke the Cookie Jar Page

:: WORK :: Document netscape emulation
Uh, turn this into pretty tables about what keys are emulated.

     (define-key w3-netscape-emulation-minor-mode-map "\M-s" 'w3-save-as)
     (define-key w3-netscape-emulation-minor-mode-map "\M-m" 'w3-mailto)
     (define-key w3-netscape-emulation-minor-mode-map "\M-n" 'make-frame)
     (define-key w3-netscape-emulation-minor-mode-map "\M-l" 'w3-fetch)
     (define-key w3-netscape-emulation-minor-mode-map "\M-o" 'w3-open-local)
     (define-key w3-netscape-emulation-minor-mode-map "\M-p" 'w3-print-this-url)
     (define-key w3-netscape-emulation-minor-mode-map "\M-q" 'w3-quit)
     (define-key w3-netscape-emulation-minor-mode-map "\M-f" 'w3-search-forward)
     (define-key w3-netscape-emulation-minor-mode-map "\M-g" 'w3-search-again)
     (define-key w3-netscape-emulation-minor-mode-map "\M-r" 'w3-reload-document)
     (define-key w3-netscape-emulation-minor-mode-map "\M-i" 'w3-load-delayed-images)
     (define-key w3-netscape-emulation-minor-mode-map "\M-a" 'w3-hotlist-add-document)
     (define-key w3-netscape-emulation-minor-mode-map "\M-b" 'w3-show-hotlist)
     (define-key w3-netscape-emulation-minor-mode-map "\M-h" 'w3-show-history-list)

Hotlist Handling
================

   :: WORK :: Document that it supports different types of hotlist
formats
:: WORK :: Make sure everything hotlist related can be accessed via 'h'
In order to avoid having to traverse many documents to get to the same
document over and over, Emacs/W3 supports a "hotlist" like Mosaic.
This is a file that contains URLs and aliases.  Hotlists allow quick
access to any document in the Web, providing it has been visited and
added to the hotlist.  The variable `w3-hotlist-file' determines where
this information is saved.  The structure of the file is compatible
with Mosaic's hotlist file, so this defaults to
`~/.mosaic-hotlist-default'.

   Hotlist commands are:
`a'
     Adds the current document to the hotlist, with the buffer name as
     its identifier.  Modifies the file specified by `w3-hotlist-file'.
     If this is given a prefix-argument (via `C-u'), the title is
     prompted for instead of automatically defaulting to the document
     title.

`hR'
     This rereads the default hostlist file specified by
     `w3-hotlist-file'.

`d'
     Prompts for the alias of the entry to kill.  Pressing the spacebar
     or tab will list out partial completions.  The internal
     representation of the hotlist and the file specified by
     `w3-hotlist-file' are updated.

`hr'
     Some hotlist item names can be very unwieldy (`Mosaic for X level
     2 fill out form support'), or uninformative (`Index of /').
     Prompts for the item to rename in the minibuffer--use the spacebar
     or tab key for completion.  After having chosen an item to rename,
     prompts for a new title until a unique title is entered.  Modifies
     the file specified by `w3-hotlist-file'.

`hu'
     Prompts for the alias to jump to.  Pressing the <spacebar> or
     <tab> key shows partial completions.

`hv'
     Converts the hotlist into HTML and displays it.

`ha'
     Shows the hotlist entries matching a regular expression.

`hA'
     Appends another hotlist file to the one currently in memory.

History
=======

   Almost all web browsers keep track of the URLs followed from a page,
so that it can provide forward and back buttons to keep a path of URLs
that can be traversed easily.

   If the variable `url-keep-history' is `t', then Emacs/W3 keeps a
list of all the URLs visited in a session.

   To view a listing of the history for this session of Emacs/W3, use
`M-x w3-show-history' from any buffer, and Emacs/W3 generates an HTML
document showing every URL visited since Emacs started (or cleared the
history list), and then format it.  Any of the links can be chosen and
followed to the original document.  To clear the history list, choose
'Clear History' from the 'Options' menu.

   Another twist on the history list mechanism is the fact that all
Emacs/W3 buffers remember what URL, buffer, and buffer position of the
last document, and also keeps track of the next location jumped to from
that buffer.  This means that the user can go forwards and backwards
very easily along the path taken to reach a particular document.  To go
forward, use the function `w3-forward-in-history', to go backward, use
the function `w3-backward-in-history'.

Global History
==============

   :: WORK :: Document that the global history can have diff. formats
Most web browsers also support the idea of a "history" of URLs the user
has visited, and it displays them in a different style than normal URLs.

   If the variable `url-keep-history' is `t', then Emacs/W3 keeps a
list of all the URLs visited in a session.  The file is automatically
written to disk when exiting emacs.  The list is added to those already
in the file specified by `url-global-history-file', which defaults to
`~/.mosaic-global-history'.

   If any URL in the list is found in the file, it is not saved, but new
ones are added at the end of the file.

   The function that saves the global history list is smart enough to
notice what style of history list is being used (Netscape, Emacs/W3, or
XMosaic), and writes out the new additions appropriately.

   One of the nice things about keeping a global history files is that
Emacs/W3 can use it as a completion table.  When doing `M-x w3-fetch',
pressing the `tab' or `space' key will show all completions for a
partial URL.  This is very useful, especially for very long URLs that
are not in a hotlist, or for seeing all the pages from a particular web
site before choosing which to retrieve.

Stylesheets
***********

   The way in which Emacs/W3 formats a document is very customizable.
All formatting is now controlled by a default stylesheet set by the user
with the `w3-default-stylesheet' variable.  Emacs/W3 currently supports
the W3C recommendation for Cascading Style Sheets, Level 1 (commonly
known as CSS1) with a few experimental items from other W3C proposals.
Wherever Emacs/W3 diverges from the specification, it will be clearly
documented, and will be changed once a full standard is available.

   Support for DSSSL is progressing, but spare time is at an all-time
low.  If anyone would like to help, please contact the author.

   The following sections closely parallel the CSS1 specification so it
should be very easy to look up what Emacs/W3 supports when browsing
through the CSS1 specification.  Please note that a lot of the text in
the following sections comes directly from the specification as well.

Terminology
===========

"attribute"
     HTML attribute, ie: `align=center' - align is the attribute.

"author"
     The author of an HTML document.

"block-level element"
     An element which has a line break before and after (e.g. 'H1' in
     HTML).

"canvas"
     The part of the UA's drawing surface onto which documents are
     rendered.

"child element"
     A subelement in SGML terminology.

"contextual selector"
     A selector that matches elements based on their position in the
     document structure. A contextual selector consists of several
     simple selectors. E.g., the contextual selector 'H1.initial B'
     consists of two simple selectors, 'H1.initial' and 'B'.

"CSS"
     Cascading Style Sheets.

"declaration"
     A property (e.g. 'font-size') and a corresponding value (e.g.
     '12pt').

"designer"
     The designer of a style sheet.

"document"
     HTML document.

"element"
     HTML element.

"element type"
     A generic identifier in SGML terminology.

"fictional tag sequence"
     A tool for describing the behavior of pseudo-classes and
     pseudo-elements.

"font size"
     The size for which a font is designed. Typically, the size of a
     font is approximately equal to the distance from the bottom of the
     lowest letter with a descender to the top of the tallest letter
     with an ascender and (optionally) with a diacritical mark.

"HTML extension"
     Markup introduced by UA vendors, most often to support certain
     visual effects. The FONT, CENTER and BLINK elements are examples
     of HTML extensions, as is the BGCOLOR attribute. One of the goals
     of CSS is to provide an alternative to HTML extensions.

"inline element"
     An element which does not have a line break before and after (e.g.
     'STRONG' in HTML)

"intrinsic dimensions"
     The width and height as defined by the element itself, not imposed
     by the surroundings. In this specification it is assumed that all
     replaced elements - and only replaced elements - come with
     intrinsic dimensions.

"parent element"
     The containing element in SGML terminology.

"pseudo-element"
     Pseudo-elements are used in CSS selectors to address typographical
     items (e.g. the first line of an element) rather than structural
     elements.

"pseudo-class"
     Pseudo-classes are used in CSS selectors to allow information
     external to the HTML source (e.g. the fact that an anchor has been
     visited or not) to classify elements.

"property"
     A stylistic parameter that can be influenced through CSS.

"reader"
     The person for whom the document is rendered.

"replaced element"
     An element that the CSS formatter only knows the intrinsic
     dimensions of. In HTML, IMG, INPUT, TEXTAREA, SELECT and OBJECT
     elements can be examples of replaced elements. E.g., the content
     of the IMG element is often replaced by the image that the SRC
     attribute points to.  CSS1 does not define how the intrinsic
     dimensions are found.

"rule"
     A declaration (e.g. 'font-family: helvetica') and its selector
     (e.g. 'H1').

"selector"
     A string that identifies what elements the corresponding rule
     applies to. A selector can either be a simple selector (e.g. 'H1')
     or a contextual selector (e.g. 'H1 B') which consists of several
     simple selectors.

"SGML"
     Standard Generalized Markup Language, of which HTML is an
     application.

"simple selector"
     A selector that matches elements based on the element type and/or
     attributes, and not the element's position in the document
     structure. E.g., 'H1.initial' is a simple selector.

"style sheet"
     A collection of rules.

"UA"
     User Agent, often a web browser or web client.

"user"
     Synonymous with reader.

"weight"
     The priority of a rule.

Basic Concepts
==============

   Designing simple style sheets is easy. One needs only to know a
little HTML and some basic desktop publishing terminology. E.g., to set
the text color of 'H1' elements to blue, one can say:

       H1 { color: blue }

   The example above is a simple CSS rule. A rule consists of two main
parts: selector ('H1') and declaration ('color: blue'). The declaration
has two parts: property ('color') and value ('blue'). While the example
above tries to influence only one of the properties needed for rendering
an HTML document, it qualifies as a style sheet on its own. Combined
with other style sheets (one fundamental feature of CSS is that style
sheets are combined) it will determine the final presentation of the
document.

   The selector is the link between the HTML document and the style
sheet, and all HTML element types are possible selectors.

Pseudo-Classes/Elements
=======================

   In CSS1, style is normally attached to an element based on its
position in the document structure. This simple model is sufficient for
a wide variety of styles, but doesn't cover some common effects. The
concept of pseudo-classes and pseudo-elements extend addressing in CSS1
to allow external information to influence the formatting process.

   Pseudo-classes and pseudo-elements can be used in CSS selectors, but
do not exist in the HTML source. Rather, they are "inserted" by the UA
under certain conditions to be used for addressing in style sheets.
They are referred to as "classes" and "elements" since this is a
convenient way of describing their behavior. More specifically, their
behavior is defined by a fictional tag sequence.

   Pseudo-elements are used to address sub-parts of elements, while
pseudo-classes allow style sheets to differentiate between different
element types.

   The only support pseudo-classes in Emacs/W3 are on the anchor tag
(<a>...</a>).

   User agents commonly display newly visited anchors differently from
older ones. In CSS1, this is handled through pseudo-classes on the 'A'
element:

       A:link { color: red }       /* unvisited link */
       A:visited { color: blue }   /* visited links */
       A:active { color: lime }    /* active links */

   All 'A' elements with an 'HREF' attribute will be put into one and
only one of these groups (i.e. target anchors are not affected). UAs may
choose to move an element from 'visited' to 'link' after a certain
time. An 'active' link is one that is currently being selected (e.g. by
a mouse button press) by the reader.

   The formatting of an anchor pseudo-class is as if the class had been
inserted manually. A UA is not required to reformat a currently
displayed document due to anchor pseudo-class transitions. E.g., a style
sheet can legally specify that the 'font-size' of an 'active' link
should be larger that a 'visited' link, but the UA is not required to
dynamically reformat the document when the reader selects the 'visited'
link.

   Pseudo-class selectors do not match normal classes, and vice versa.
The style rule in the example below will therefore not have any
influence:

       A:link { color: red }

       <A CLASS=link NAME=target5> ... </A>

   In CSS1, anchor pseudo-classes have no effect on elements other than
'A'. Therefore, the element type can be omitted from the selector:

       A:link { color: red }
       :link { color: red }

   The two selectors above will select the same elements in CSS1.

   Pseudo-class names are case-insensitive.

   Pseudo-classes can be used in contextual selectors:

       A:link IMG { border: solid blue }

   Also, pseudo-classes can be combined with normal classes:

       A.external:visited { color: blue }

       <A CLASS=external HREF="http://out.side/">external link</A>

   If the link in the above example has been visited, it will be
rendered in blue. Note that normal class names precede pseudo-classes
in the selector.

The Cascade
===========

   In CSS, more than one style sheet can influence the presentation
simultaneously. There are two main reasons for this feature: modularity
and author/reader balance.

modularity
     A style sheet designer can combine several (partial) style sheets
     to reduce redundancy:

            @import url(http://www.style.org/pastoral);
            @import url(http://www.style.org/marine);

            H1 { color: red }     /* override imported sheets */

author/reader balance
     Both readers and authors can influence the presentation through
     style sheets. To do so, they use the same style sheet language
     thus reflecting a fundamental feature of the web: everyone can
     become a publisher. The UA is free to choose the mechanism for
     referencing personal style sheets.

   Sometimes conflicts will arise between the style sheets that
influence the presentation. Conflict resolution is based on each style
rule having a weight. By default, the weights of the reader's rules are
less than the weights of rules in the author's documents. I.e., if
there are conflicts between the style sheets of an incoming document
and the reader's personal sheets, the author's rules will be used. Both
reader and author rules override the UA's default values.

   The imported style sheets also cascade with each other, in the order
they are imported, according to the cascading rules defined below. Any
rules specified in the style sheet itself override rules in imported
style sheets. That is, imported style sheets are lower in the cascading
order than rules in the style sheet itself. Imported style sheets can
themselves import and override other style sheets, recursively.

   In CSS1, all '@import' statements must occur at the start of a style
sheet, before any declarations. This makes it easy to see that rules in
the style sheet itself override rules in the imported style sheets.

   NOTE: The use of !important in CSS stylesheets is unsupported at
this time.

   Conflicting rules are intrinsic to the CSS mechanism. To find the
value for an element/property combination, the following algorithm must
be followed:

  1. Find all declarations that apply to the element/property in
     question. Declarations apply if the selector matches the element in
     question. If no declarations apply, the inherited value is used. If
     there is no inherited value (this is the case for the 'HTML'
     element and for properties that do not inherit), the initial value
     is used.

  2. Sort the declarations by explicit weight: declarations marked
     '!important' carry more weight than unmarked (normal) declarations.

  3. Sort by origin: the author's style sheets override the reader's
     style sheet which override the UA's default values. An imported
     style sheet has the same origin as the style sheet from which it
     is imported.

  4. Sort by specificity of selector: more specific selectors will
     override more general ones. To find the specificity, count the
     number of ID attributes in the selector (a), the number of CLASS
     attributes in the selector (b), and the number of tag names in the
     selector (c). Concatenating the three numbers (in a number system
     with a large base) gives the specificity. Some examples:
            LI            {...}  /* a=0 b=0 c=1 -> specificity =   1 */
            UL LI         {...}  /* a=0 b=0 c=2 -> specificity =   2 */
            UL OL LI      {...}  /* a=0 b=0 c=3 -> specificity =   3 */
            LI.red        {...}  /* a=0 b=1 c=1 -> specificity =  11 */
            UL OL LI.red  {...}  /* a=0 b=1 c=3 -> specificity =  13 */
            #x34y         {...}  /* a=1 b=0 c=0 -> specificity = 100 */
     Pseudo-elements and pseudo-classes are counted as normal elements
     and classes, respectively.

  5. Sort by order specified: if two rules have the same weight, the
     latter specified wins. Rules in imported style sheets are
     considered to be before any rules in the style sheet itself.

   The search for the property value can be terminated whenever one rule
has a higher weight than the other rules that apply to the same
element/property combination.

   This strategy gives author's style sheets considerably higher weight
than those of the reader. It is therefore important that the reader has
the ability to turn off the influence of a certain style sheet, e.g.
through a pull-down menu.

   A declaration in the 'STYLE' attribute of an element has the same
weight as a declaration with an ID-based selector that is specified at
the end of the style sheet:

     <STYLE TYPE="text/css">
       #x97z { color: blue }
     </STYLE>

     <P ID=x97z STYLE="color: red">

   In the above example, the color of the 'P' element would be red.
Although the specificity is the same for both declarations, the
declaration in the 'STYLE' attribute will override the one in the
'STYLE' element because of cascading rule number 5.

   The UA may choose to honor other stylistic HTML attributes, for
example 'ALIGN'. If so, these attributes are translated to the
corresponding CSS rules with specificity equal to 1. The rules are
assumed to be at the start of the author style sheet and may be
overridden by subsequent style sheet rules. In a transition phase, this
policy will make it easier for stylistic attributes to coexist with
style sheets.

Properties
==========

   In the text below, the allowed values for each property are listed
with a syntax like the following:

           Value: N | NW | NE
           Value: [ <length> | thick | thin ]{1,4}
           Value: <uri>? <color> [ / <color> ]?
           Value: <uri> || <color>

   The words between < and > give a type of value. The most common types
are <length>, <percentage>, <url>, <number>and <color> these are
described in the section on [[units]]. The more specialized types (e.g.
<font-family>and <border-style>) are described under the property where
they appear.

   Other words are keywords that must appear literally, without quotes.
The slash (/) and the comma (,) must also appear literally.

   Several things juxtaposed mean that all of them must occur, in the
given order. A bar (|) separates alternatives: one of them must occur. A
double bar (A || B) means that either A or B or both must occur, in any
order. Brackets ([]) are for grouping. Juxtaposition is stronger than
the double bar, and the double bar is stronger than the bar. Thus "a b |
c || d e" is equivalent to "[ a b ] | [ c || [ d e ]]".

   Every type, keyword, or bracketed group may be followed by one of the
following modifiers:

   * An asterisk (*) indicates that the preceding type, word or group is
     repeated zero or more times.

   * A plus (+) indicates that the preceding type, word or group is
     repeated one or more times.

   * A question mark (?) indicates that the preceding type, word or
     group is optional.

   * A pair of numbers in curly braces ({A,B}) indicates that the
     preceding type, word or group is repeated at least A and at most B
     times.

   Other than the value the following information is also shown.

Supported      If this is present, it lists the parts of the
Values:        specification that Emacs/W3 currently supports.
Unsupported    If this is present, it represents the parts of the
Values:        specifcation that Emacs/W3 does not support.
Initial:       The default value for the property, unless explicitly set
               in a stylesheet.
Applies to:    What type of elements this property can be attached to.
Inherited:     Yes or no
Percentage     What a percentage value applies to when given.
values:

Font Properties
---------------

   Setting font properties will be among the most common uses of style
sheets.  Unfortunately, there exists no well-defined and universally
accepted taxonomy for classifying fonts, and terms that apply to one
font family may not be appropriate for others. E.g. 'italic' is commonly
used to label slanted text, but slanted text may also be labeled as
being Oblique, Slanted, Incline, Cursive or Kursiv. Therefore it is not
a simple problem to map typical font selection properties to a specific
font.

   The properties defined by CSS1 are described in the following
sections.

font-family
...........

Supported      [[<family-name> | <generic-family>],]* [<family-name> |
Values:        <generic-family>]
Initial:       User specific
Applies to:    all elements
Inherited:     yes
Percentage     N/A
values:

   The value is a prioritized list of font family names and/or generic
family names. Unlike most other CSS1 properties, values are separated
by a comma to indicate that they are alternatives:

       BODY { font-family: gill, helvetica, sans-serif }

   There are two types of list values:

<family-name>
     The name of a font family of choice. In the last example, "gill"
     and "helvetica" are font families.

<generic-family>
     In the example above, the last value is a generic family name. The
     following generic families are defined:
        * 'serif' (e.g. Times)

        * 'sans-serif' (e.g. Helvetica)

        * 'cursive' (e.g. Zapf-Chancery)

        * 'fantasy' (e.g. Western)

        * 'monospace' (e.g. Courier)

   Style sheet designers are encouraged to offer a generic font family
as a last alternative.

   Font names containing whitespace should be quoted:

       BODY { font-family: "new century schoolbook", serif }

       <BODY STYLE="font-family: 'My own font', fantasy">

   If quoting is omitted, any whitespace characters before and after the
font name are ignored and any sequence of whitespace characters inside
the font name is converted to a single space.

font-style
..........

Supported      normal | italic | oblique
Values:
Initial:       normal
Applies to:    all elements
Inherited:     yes
Percentage     N/A
values:

   The 'font-style' property selects between normal (sometimes referred
to as "roman" or "upright"), italic and oblique faces within a font
family.

   A value of 'normal' selects a font that is classified as 'normal' in
the UA's font database, while 'oblique' selects a font that is labeled
'oblique'. A value of 'italic' selects a font that is labeled 'italic',
or, if that is not available, one labeled 'oblique'.

   The font that is labeled 'oblique' in the UA's font database may
actually have been generated by electronically slanting a normal font.

   Fonts with Oblique, Slanted or Incline in their names will typically
be labeled 'oblique' in the UA's font database. Fonts with Italic,
Cursive or Kursiv in their names will typically be labeled 'italic'.

       H1, H2, H3 { font-style: italic }
       H1 EM { font-style: normal }

   In the example above, emphasized text within 'H1' will appear in a
normal face.